package net.big_oh.common.jdbc.event.listener;

import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.EventListener;

import net.big_oh.common.jdbc.JdbcDriverProxy;
import net.big_oh.common.jdbc.event.ConnectionInstantiationEvent;
import net.big_oh.common.jdbc.event.SQLExecutionEvent;
import net.big_oh.common.jdbc.event.StatementInstantiationEvent;


/*
 Copyright (c) 2009 Dave Wingate dba Big-Oh Software (www.big-oh.net)

 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation
 files (the "Software"), to deal in the Software without
 restriction, including without limitation the rights to use,
 copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the
 Software is furnished to do so, subject to the following
 conditions:

 The above copyright notice and this permission notice shall be
 included in all copies or substantial portions of the Software.

 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
 */

/**
 * An EventListener that observes events generated by the
 * {@link JdbcDriverProxy} class.
 * 
 * @author davewingate
 * 
 */
public interface JDBCEventListener extends EventListener
{

	/**
	 * Called prior to instantiating a new Connection.
	 * 
	 * @param event
	 *            The event encapsulating the request for a new
	 *            {@link Connection}.
	 */
	public void connectionRequested(ConnectionInstantiationEvent event);

	/**
	 * Called after instantiating a new Connection.
	 * 
	 * @param event
	 *            The event encapsulating the request for a new
	 *            {@link Connection}.
	 * @param newConnection
	 *            The new Connection that was instantiated.
	 */
	public void connectionInstantiated(ConnectionInstantiationEvent event, Connection newConnection);

	/**
	 * Called prior to instantiating a new Statement.
	 * 
	 * @param event
	 *            The event encapsulating the request for a new
	 *            {@link Statement}.
	 */
	public void statementRequested(StatementInstantiationEvent event);

	/**
	 * Called after instantiating a new Statement.
	 * 
	 * @param event
	 *            The event encapsulating the request for a new
	 *            {@link Statement}.
	 * @param newStatement
	 *            The new Statement that was instantiated.
	 */
	public void statementInstantiated(StatementInstantiationEvent event, Statement newStatement);

	/**
	 * Called prior to executing SQL statement(s).
	 * 
	 * @param event
	 *            The event encapsulating the request to execute one or more SQL
	 *            commands.
	 * @throws SQLException
	 *             Throw this exception to prevent execution of the SQL
	 *             statements wrapped in the SQLExecutionEvent event.
	 */
	public void beforeSQLExecution(SQLExecutionEvent event) throws SQLException;

	/**
	 * Called after executing SQL statement(s).
	 * 
	 * @param event
	 *            The event encapsulating the request to execute one or more SQL
	 *            commands.
	 */
	public void afterSQLExecution(SQLExecutionEvent event);

}
